# Preliminary Release of IceCat-2 

This preliminary data release contains alerts previously presented at ICRC ([PoS(ICRC2025)1224](https://pos.sissa.it/501/1224/pdf)):

- **IC-170922A** — in spatial coincidence with the blazar TXS 0506+056, representing the first association between a neutrino alert and an astrophysical source.

- **IC-220424A** and **IC-230416A** — in spatial coincidence with NGC 7469.

- **IC-200530A**, **IC-191119A**, and **IC-191001A** — previously identified in spatial coincidence with several Tidal Disruption Events.

- In addition to these events, we also include **IC-230724A** in this preliminary release. Its inclusion is motivated by the fact that it was a promising Gold alert, with an average probability of astrophysical origin of 53%. An issue in the automatic processing pipeline responsible for the offline reconstruction delayed the distribution of its updated position ([GCN Circular 34265](https://gcn.nasa.gov/circulars/34265)). To ensure timely availability at the time, an alternative reconstruction algorithm was applied. Following the update of the reconstruction algorithms for high-energy track alerts in September 2024 ([IceCube Update Doc](https://roc.icecube.wisc.edu/public/docs/IceCube_Update_Muon_Alert_Reco.pdf)), the new position and the alert-related parameters have now been recalculated.

## Project content

In the following, there is the explanation of the content of the ```dataverse_files``` folder.

### CSV table

Each alert catalog entry is represented by an entry in a summary CSV table (```Table_Preliminary_Release.csv```).

For each event, the CSV table contains:
- ```NAME```: Unique name given to each alert, in form ICYYMMDDA - RUNID,EVENTID: Unique RunID and EventID combination from IceCube data acquisition system
- ```START```,```EVENTMJD```: Date/time of event detection
- ```I3TYPE```: Identification of event selection type (see IceCat-1 paper publication for details). gfu-gold, gfu-bronze, ehe-gold, hese-gold, or hese-bronze types
- ```OTHER_I3TYPES```: List of other I3TYPE event selection types this event additionally passed.
- ```RA```,```DEC``` [deg] (and ```_ERR_50```, ```ERR_90```): Best fit direction in J2000 equatorial coordinates, with asymmetric 50% and 90% CL error rectangle boundaries.
- ```CONTOUR AREA (50%)```,```CONTOUR AREA (90%)``` [sdeg]: Contour area of uncertainty contours at 50% and 90% confidence levels around the best-fit direction.
- ```ENERGY``` [TeV]: Most probable neutrino energy that would have produced this event. Calculated assuming an E^(-2.19) astrophysical neutrino power law flux.
- ```FAR``` [yr^(-1)]: Rate of background events expected for alert events at this energy and sky location.
- ```P_ASTRO```: Probability event is of astrophysical origin, calculated assuming an E^(-2.19) astrophysical neutrino power law flux.

### FITS files

For each event, two FITS files are provided, corresponding to two different way of saving the probability distributions for the or the true direction of the neutrino event. This represents a change relative to the previous IceCube track-alert release (IceCat-1),where likelihood maps were provided. The new format directly encodes the sky probability distribution, improving compatibility with follow-up instruments and multimessenger analysis tools.

- **Multi-order probability map (MOC/HEALPix):** The probability distribution is stored using the HEALPix multi-order (multi-resolution) format. This format retains the pixels originally scanned by IceCube with their original areas. Areas nearby the best-fit direction were scanned useing a finer pixelization while further away a coarser pixelization is used. This ensures efficient storage while preserving the accuracy of the probability distribution. The probability assigned to each pixel represents the probability density, so that multiplying it by the pixel area and summing over all pixels yields 1.

- **Flat skymap:** A HEALPix skymap in which all pixels have the same area. Pixels that are larger than the maximum defined resolution are subdivided into smaller pixels until it is is reached, so that every pixel has the same area. This provides a uniform representation of the sky, but results in comparatively large file sizes since since all pixels have the highest resolution. The total information content is the same as in the multi-order map, but here the probability is stored directly per pixel, so summing over all pixel values gives 1. The uniform high resolution results in comparatively large file sizes, making flat maps less storage-efficient, though they remain convenient for quick use and simple plotting.

Information equivalent to that in the CSV files is also stored in the headers of the FITS files.

IceCat-1 paper: R. Abbasi et al., 2023, *ApJS*, 269, 25 ([DOI: 10.3847/1538-4365/acfa95](https://doi.org/10.3847/1538-4365/acfa95))

### Contours

For each event, uncertainty contours at 50% and 90% confidence levels around the best-fit direction are provided. These contours are derived from the probability maps and are saved in both `.pkl` and `.txt` formats.

- **Pickle files (`.pkl`)**: contain arrays for right ascension (RA), declination (Dec), and the corresponding contour levels. These files are convenient for programmatic access and further processing in Python.  
- **Text files (`.txt`)**: two separate files are provided for each event, one for the 50% contour and another for the 90% contour. These files contain the same RA and Dec coordinates defining the contour and are suitable for quick inspection or use with external plotting tools.

### Jupyter Notebook

This Jupyter notebook serves as an example for handling IceCat-2 multi-order maps, showing how to:

- Extract data from the header of the multi-order map.
- Calculate the most probable sky location (pixel with the highest probability), which corresponds to the best-fit directions saved in the header.
- Extract 50% and 90% containment regions around the best-fit direction.
- Plot the entire skymap as well as a zoomed view around the best-fit direction.
- Part of this Jupyter notebook is inspired by the GCN multi-order HEALPix maps documentation https://gcn.nasa.gov/docs/sample/healpix. We leverage mhealpy (https://mhealpy.readthedocs.io/en/latest/) to efficiently handle multi-order HEALPix maps, including operations such as rasterization, pixel area calculation, and visualization.

The following section provides guidance on how to correctly install all packages needed to run this notebook.

#### Using a Python Environment

1. **Create and activate a new source environment**

```bash
python3.11 -m venv .icecat
source .icecat/bin/activate
```

2. **Install packages from requirements.txt**

```pip install -r requirements.txt```

3. **Launch jupyter notebook or Jupyter lab**

```pip install notebook``` or ```pip install jupyterlab```

4. **Launch jupyter notebook or Jupyter lab**

```jupyter notebook``` or ```jupyter lab```


#### Using a Conda Environment

1. **Create and activate a new conda environment**

```bash
conda create -n icecat python=3.11
conda activate icecat
```

2. **Install packages from requirements.txt**

```pip install -r requirements.txt```

3. **Launch jupyter notebook or Jupyter lab**

```pip install notebook``` or ```pip install jupyterlab```

4. **Launch jupyter notebook or Jupyter lab**

```jupyter notebook``` or ```jupyter lab```


### plots

In addition, PDF plots are provided, including full-sky maps in Mollweide projection and zoomed views around the best-fit directions. The zoomed maps also display known gamma-ray sources from the [Fermi 4FGL catalog](https://fermi.gsfc.nasa.gov/ssc/data/access/lat/14yr_catalog/) that are located near the IceCube alert.
